feat(codex): persist reset-credit operation identity - #1526

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/codex/auth-api.ts`:
- Around line 1775-1780: In src/codex/auth-api.ts:1775-1780, integrate
CodexResetCreditRecoveryGeneration with openResetCreditOperation before
consumeCodexResetCredit, reuse the reserved operationId, return stored terminal
outcomes without dispatching upstream, settle terminal results, and mark
ambiguous transport failures while preserving fail-closed state. In
tests/codex-auth-api.test.ts:2198-2201, add an ambiguous-transport retry case
asserting only one upstream consume and reuse of the same redeem_request_id.

In `@src/codex/reset-credit-operation-ledger.ts`:
- Around line 389-391: In src/codex/reset-credit-operation-ledger.ts lines
389-391, update the catch handler to capture the error and warn for every cause
except SQLITE_BUSY, using only the ledger’s own error strings; apply the same
change to the second handler at lines 425-427. In src/config.ts lines 2414-2422,
enforce the documented precondition in the config-mutation flow by throwing when
configMutationLockDepth > 0, so nested mutations surface as errors.
- Around line 430-464: Document the public throw-versus-return contract for
markResetCreditOperationAmbiguous, openResetCreditOperation, and
settleResetCreditOperation. State that invalid now values and invalid
generations throw TypeError, while invalid operation IDs or non-terminal settle
codes return the existing mismatch result, keeping the current behavior
unchanged.
- Around line 15-20: Replace TERMINAL_CODES with an exhaustive
Record<CodexResetCreditConsumeCode, "confirmed" | "stopped">, assigning each
consume code its terminal state so future enum members require compiler updates.
Update terminal membership checks and state validation in
settleResetCreditOperation, including the mappings around lines 165-166 and 459,
to derive behavior from this record rather than set membership.
- Around line 282-293: Reuse the existing compareGenerationOrder comparator in
compareGeneration instead of maintaining duplicate lexicographic ordering logic.
Import or otherwise expose compareGenerationOrder as needed, and preserve the
current credentialGeneration-then-exhaustionGeneration ordering contract.
- Around line 197-208: Update the table_xinfo query in the reset-credit
operation ledger validation to interpolate or otherwise use the existing
TABLE_NAME constant instead of the hardcoded reset_credit_operations identifier,
while preserving the current column retrieval and validation flow.
- Around line 305-306: Update the withLedger callback type to reject inferred
PromiseLike results at compile time, while preserving synchronous return values
and the existing runtime guard. Ensure async callbacks and direct promise
returns fail type checking rather than reaching the surrounding catch path.
- Around line 57-67: Add a regression test in the reset credit operation ledger
test suite that creates a fresh table and asserts its main.sqlite_schema.sql
equals the EXPECTED_SCHEMA_SQL value derived from CREATE_TABLE.replace("main.",
""). Reuse the existing table-opening/setup path and verify the schema contract
before exercising openResetCreditOperation.

In `@src/codex/reset-credit-recovery.ts`:
- Around line 487-493: Make createLogicalTurnForOperation require a branded
reserved-operation-id type rather than a plain string, while retaining its
existing UUID validation and restoration behavior. Define the brand near the
recovery types and expose a controlled conversion usable only by
openResetCreditOperation; return the branded value from that function’s execute
and terminal results so arbitrary UUIDs cannot reach the restoration seam
without a ledger-issued token.

In `@src/config.ts`:
- Around line 2414-2422: Enforce the documented non-nesting precondition in
prepareConfigMutationDatabasePathForWrite by checking configMutationLockDepth
and throwing a clear error when called while withConfigMutationLockSync is
active; otherwise preserve the existing database-path return. Ensure the related
withLedger error-reporting path surfaces this specific failure rather than
leaving it indistinguishable from ordinary SQLITE_BUSY contention.

In `@tests/codex-reset-credit-operation-ledger.test.ts`:
- Around line 234-242: Move the holder.exec call that sets busy_timeout and
begins the transaction inside the existing try block so holder.close() is always
reached via finally. Because ROLLBACK can fail when BEGIN IMMEDIATE did not open
a transaction, guard or otherwise suppress rollback errors while ensuring
holder.close() still executes.
- Around line 37-63: Add a focused regression test near the existing
duplicate-ledger tests that uses the canonical schema, creates a reservation for
one account, inserts the same operationId under a different account, and
verifies subsequent openResetCreditOperation calls fail closed with unavailable.
Keep createLaxDuplicateLedger for schema-validation coverage and exercise
initializeTable’s cross-account operationIds rejection path.
- Around line 105-112: Add an assertion to the recovery test around
coordinator.recover and settleResetCreditOperation that explicitly verifies the
durable ledger remains pending after recovery while terminalByAccount contains
the terminal fence, documenting this intentional boundary without changing
production behavior. Use the existing ledger lookup and coordinator state
symbols rather than adding new flows.
- Around line 289-304: Update the overflow-row setup in the test to derive its
operation_id from MAX_RESET_CREDIT_OPERATION_ACCOUNTS using a value beyond the
loop’s generated index range, rather than hardcoding a potentially colliding
suffix. Add a concise comment documenting that this over-capacity test relies on
SELECT_ALL fetching MAX_RESET_CREDIT_OPERATION_ACCOUNTS + 1 rows so the capacity
check is exercised.
- Around line 24-35: Update corruptFirstRecord to remove the LIMIT 1 clause from
its UPDATE statement, leaving the existing single-row test setup and
databasePath implementation unchanged.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/codex/auth-api.ts`:
- Around line 1822-1858: Replace every inline server-busy response construction
in the route, including the branches around openManualResetCreditOperation,
settleManualResetCreditOperation, and the catch block, with calls to the
existing manualResetCreditBusyResponse() helper. Preserve the current return
behavior at each site and use the helper for the complete 503 response contract.

In `@src/codex/reset-credit-operation-ledger.ts`:
- Around line 513-520: Replace the literal error.message comparison in
warnLedgerUnavailable with a shared error identity from config.ts: export a
dedicated error class or message constant at the existing nested-mutation throw
site, then import and use it here. Preserve the current nested diagnostic and
generic unavailable log behavior, without logging sensitive data.
- Around line 245-251: Update the validation logic around terminalState in the
record parser so non-terminal states require code to be null, rejecting any
unrecognized or non-null code instead of dropping it. Preserve the existing
terminal-state mapping and validation behavior, and add a focused malformed-row
regression beside the existing tests for this ledger subsystem.
- Around line 726-753: Make the terminal current-record/new-operationId path
explicit in the manual operation decision logic: retain the execute return for
non-terminal records, the terminal return for same-operation retries, and
explicitly return a fresh non-resumed execute result for a distinct operationId
after a terminal record. Update the corresponding record replacement flow as
needed, and add a focused regression beside the existing manual tests covering
settlement of one operationId followed by a distinct operationId for the same
account, asserting execute with resumed false and the new id.

In `@src/codex/reset-credit-recovery.ts`:
- Around line 37-42: Enforce canonical lowercase IDs in
CODEX_RESET_CREDIT_OPERATION_ID_PATTERN by removing case-insensitive matching,
so isCodexResetCreditOperationId rejects uppercase hexadecimal values before
ledger operations. Add coverage for an uppercase terminal ID followed by a
lowercase retry, preserving case-sensitive behavior in
SELECT_KEY_BY_OPERATION_ID, UPDATE_RECORD, and updateOperation.

In `@tests/codex-reset-credit-operation-ledger.test.ts`:
- Around line 107-123: Extend the migration test around migrateLegacyTable to
assert the reopened reset_credit_operations schema exactly matches
RESET_CREDIT_OPERATION_SCHEMA_SQL_FOR_TESTS and that
reset_credit_operations_legacy_v1 no longer exists. Keep the existing
migrated-row assertions, and use the canonical schema/absence checks to cover
both structural migration output and legacy-table cleanup.

---

Outside diff comments:
In `@src/codex/reset-credit-recovery.ts`:
- Around line 489-510: Move the isCodexResetCreditOperationId validation and
existing TypeError message from createLogicalTurnForOperation into the shared
private registerLogicalTurn method, applying it before the turn is stored.
Remove the duplicate check from createLogicalTurnForOperation so both
createLogicalTurn and createLogicalTurnForOperation enforce the same operation
identity invariant through registerLogicalTurn.